/*
 *  Copyright 2004 Blandware (http://www.blandware.com)
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */
package com.blandware.atleap.service.core;

import com.blandware.atleap.common.util.PartialCollection;
import com.blandware.atleap.common.util.QueryInfo;
import com.blandware.atleap.model.core.Layout;
import com.blandware.atleap.model.core.TileContainer;
import com.blandware.atleap.persistence.exception.DeleteException;
import com.blandware.atleap.persistence.exception.UpdateException;
import com.blandware.atleap.service.exception.BeanAlreadyExistsException;
import com.blandware.atleap.service.exception.BeanNotFoundException;

import java.util.List;

/**
 * <p>Business Delegate (Proxy) Interface to handle communication between web and
 * persistence layer.
 * </p>
 * <p><a href="LayoutManager.java.html"><i>View Source</i></a>
 * </p>
 *
 * @author Sergey Zubtsovskiy <a href="mailto:sergey.zubtsovskiy@blandware.com">&lt;sergey.zubtsovskiy@blandware.com&gt;</a>
 * @version $Revision: 1.11 $ $Date: 2007/04/08 15:07:14 $
 */
public interface LayoutManager extends BaseManager {
    
    //  L A Y O U T S

    //~ CRUD Methods ================================================================

	/**
	 * Creates new layout
	 *
	 * @param layout Layout to create
	 * @return ID of created layout
	 * @throws BeanAlreadyExistsException if layout with the same definition or name already exist
	 */
	public Long createLayout(Layout layout) throws BeanAlreadyExistsException;

	/**
	 * Retrieves layout with specified ID
	 *
	 * @param layoutId ID of layout to retrieve
	 * @return Layout or null if no layout with specified ID exists in database
	 */
	public Layout retrieveLayout(Long layoutId);

	/**
	 * Updates layout
	 *
	 * @param layout Layout to update
	 * @throws BeanAlreadyExistsException if layout with the same definition or name already exist
	 * @throws BeanNotFoundException      if layout with specified ID couldn't be found
     * @throws com.blandware.atleap.persistence.exception.UpdateException Thrown
     * if update is invalid
	 */
	public void updateLayout(Layout layout) throws BeanAlreadyExistsException, BeanNotFoundException, UpdateException;

	/**
	 * Removes layout
	 *
	 * @param layoutId ID of layout to remove
	 * @throws DeleteException if layout cannot be deleted (e.g. there is one or more content page
	 *                         based on it)
     * @throws com.blandware.atleap.service.exception.BeanNotFoundException if
     * no such layout exists
	 */
	public void deleteLayout(Long layoutId) throws DeleteException, BeanNotFoundException;

	// ~ Additional methods ================================================================

	/**
	 * Retrieves filtered/sorted collection of layouts
	 *
	 * @param queryInfo Object that contains information about how to filter and sort data
	 * @return Collection of layouts
	 */
	public PartialCollection listLayouts(QueryInfo queryInfo);

	// ~ Finders ================================================================

	/**
	 * Finds layout by content page URI
	 *
	 * @param contentPageUri URI of content page to find layout
	 * @return Layout or null if nothing was found
	 */
	public Layout findLayoutByContentPageUri(String contentPageUri);

	/**
	 * Finds layout by name of Struts tile definition name
	 *
	 * @param definitionName Name of definition to search by
	 * @return Layout or null if nothing was found
	 */
	public Layout findLayoutByDefinition(String definitionName);

	/**
	 * Finds layout by its name
	 *
	 * @param name Name of layout to search by
	 * @return Layout or null if nothing was found
	 */
	public Layout findLayoutByName(String name);

    //  T I L E   C O N T A I N E R S

    //~ CRUD Methods ================================================================

    /**
     * Creates new container.
     *
     * @param container TileContainer to create
     * @param layoutId ID of layout on which to create container
     * @return ID of created container
     * @throws BeanAlreadyExistsException if container with the same
     * definition-list pair already exist on layout with given ID
     * @throws com.blandware.atleap.service.exception.BeanNotFoundException if
     * no such layout exists
     */
    public Long createTileContainer(TileContainer container, Long layoutId)
            throws BeanAlreadyExistsException, BeanNotFoundException;

	/**
	 * Retrieves tile container with specified ID.
	 *
	 * @param tileContainerId ID of tile container to retrieve
	 * @return Tile container or null if no container with specified ID exists
     * in database
	 */
	public TileContainer retrieveTileContainer(Long tileContainerId);

    /**
	 * Updates tile container.
	 *
	 * @param tileContainer container to update
	 * @throws BeanAlreadyExistsException if container with the same definition
     * and list names already exists on same layout
	 * @throws BeanNotFoundException      if container with specified ID
     * couldn't be found
	 */
	public void updateTileContainer(TileContainer tileContainer)
            throws BeanAlreadyExistsException, BeanNotFoundException;

    /**
     * Removes container.
     *
     * @param containerId ID of container to remove
     * @throws com.blandware.atleap.service.exception.BeanNotFoundException if
     * no such container exists
     */
    public void deleteTileContainer(Long containerId) throws BeanNotFoundException;

	// ~ Additional methods ================================================================

	/**
	 * Retrieves filtered/sorted collection of tile containers.
	 *
	 * @param queryInfo Object that contains information about how to filter
     * and sort data
	 * @return Collection of tile containers
	 */
	public PartialCollection listTileContainers(QueryInfo queryInfo);

    // ~ Finders ================================================================

    /**
     * Returns a list of containers which belong to layout with a given ID.
     *
     * @param layoutId ID of layout to search by
     * @return list of containers
     */
    public List findTileContainersByLayoutId(Long layoutId);

    /**
     * Returns a container which belongs to layout with a given ID and has
     * given full identifier.
     *
     * @param layoutId ID of layout to search by
     * @param identifier full identifier to search by
     * @return tile container or null if not found
     */
    public TileContainer findTileContainerByLayoutIdAndIdentifier(Long layoutId,
            String identifier);
}
